SGI Freeware 1999 August/SGI Freeware 1999 August.iso/dist/fw_perl.idb/usr/freeware/catman/p_man/cat3/IO::Socket.Z/IO::Socket

Text File | 1998-10-28 | 9.9 KB | 331 lines

     IIIIOOOO::::::::SSSSoooocccckkkkeeeetttt((((3333))))   22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))     IIIIOOOO::::::::SSSSoooocccckkkkeeeetttt((((3333))))



     NNNNAAAAMMMMEEEE
      IO::Socket - Object interface    to socket communications

     SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
          use IO::Socket;


     DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
      IO::Socket provides an object    interface to creating and
      using    sockets. It is built upon the the _I_O::_H_a_n_d_l_e manpage
      interface and    inherits all the methods defined by the
      _I_O::_H_a_n_d_l_e manpage.

      IO::Socket only defines methods for those operations which
      are common to    all types of socket. Operations    which are
      specified to a socket    in a particular    domain have methods
      defined in sub classes of IO::Socket

      IO::Socket will export all functions (and constants) defined
      by the _S_o_c_k_e_t    manpage.

     CCCCOOOONNNNSSSSTTTTRRRRUUUUCCCCTTTTOOOORRRR
      new (    [ARGS] )
          Creates an IO::Socket, which is a    reference to a newly
          created symbol (see the Symbol package). new optionally
          takes arguments, these arguments are in key-value    pairs.
          new only looks for one key Domain    which tells new    which
          domain the socket    will be    in. All    other arguments    will
          be passed    to the configuration method of the package for
          that domain, See below.

          IO::Sockets will be in autoflush mode after creation.
          Note that    versions of IO::Socket prior to    1.1603 (as
          shipped with Perl    5.004_04) did not do this.   So    if you
          need backward compatibility, you should set autoflush
          explicitly.

     MMMMEEEETTTTHHHHOOOODDDDSSSS
      See the _p_e_r_l_f_u_n_c manpage for complete    descriptions of    each
      of the following supported IO::Socket    methods, which are
      just front ends for the corresponding    built-in functions:

          socket
          socketpair
          bind
          listen
          accept
          send
          recv
          peername (getpeername)
          sockname (getsockname)




     Page 1                        (printed 10/23/98)






     IIIIOOOO::::::::SSSSoooocccckkkkeeeetttt((((3333))))   22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))     IIIIOOOO::::::::SSSSoooocccckkkkeeeetttt((((3333))))



      Some methods take slightly different arguments to those
      defined in the _p_e_r_l_f_u_n_c manpage in attempt to    make the
      interface more flexible. These are

      accept([PKG])
          perform the system call accept on    the socket and return
          a    new object. The    new object will    be created in the same
          class as the listen socket, unless PKG is    specified.
          This object can be used to communicate with the client
          that was trying to connect. In a scalar context the new
          socket is    returned, or undef upon    failure. In an array
          context a    two-element array is returned containing the
          new socket and the peer address, the list    will be    empty
          upon failure.

          Additional methods that are provided are

      timeout([VAL])
          Set or get the timeout value associated with this
          socket. If called    without    any arguments then the current
          setting is returned. If called with an argument the
          current setting is changed and the previous value
          returned.

      sockopt(OPT [, VAL])
          Unified method to    both set and get options in the
          SOL_SOCKET level.    If called with one argument then
          getsockopt is called, otherwise setsockopt is called.

      sockdomain
          Returns the numerical number for the socket domain type.
          For example, for a AF_INET socket    the value of &AF_INET
          will be returned.

      socktype
          Returns the numerical number for the socket type.    For
          example, for a SOCK_STREAM socket    the value of
          &SOCK_STREAM will    be returned.

      protocol
          Returns the numerical number for the protocol being used
          on the socket, if    known. If the protocol is unknown, as
          with an AF_UNIX socket, zero is returned.

     SSSSUUUUBBBB----CCCCLLLLAAAASSSSSSSSEEEESSSS
      IIIIOOOO::::::::SSSSoooocccckkkkeeeetttt::::::::IIIINNNNEEEETTTT

      IO::Socket::INET provides a constructor to create an AF_INET
      domain socket    and some related methods. The constructor can
      take the following options





     Page 2                        (printed 10/23/98)






     IIIIOOOO::::::::SSSSoooocccckkkkeeeetttt((((3333))))   22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))     IIIIOOOO::::::::SSSSoooocccckkkkeeeetttt((((3333))))



          PeerAddr      Remote host address           <hostname>[:<port>]
          PeerPort      Remote port or service       <service>[(<no>)] | <no>
          LocalAddr      Local    host bind address      hostname[:port]
          LocalPort      Local    host bind port           <service>[(<no>)] | <no>
          Proto      Protocol name    (or number)    "tcp" | "udp" | ...
          Type      Socket type               SOCK_STREAM | SOCK_DGRAM    | ...
          Listen      Queue    size for listen
          Reuse      Set SO_REUSEADDR before binding
          Timeout      Timeout value    for various operations

      If Listen is defined then a listen socket is created,    else
      if the socket    type, which is derived from the    protocol, is
      SOCK_STREAM then _c_o_n_n_e_c_t() is    called.

      The PeerAddr can be a    hostname or the    IP-address on the
      "xx.xx.xx.xx"    form.  The PeerPort can    be a number or a
      symbolic service name.  The service name might be followed
      by a number in parenthesis which is used if the service is
      not known by the system.  The    PeerPort specification can
      also be embedded in the PeerAddr by preceding    it with    a ":".

      If Proto is not given    and you    specify    a symbolic PeerPort
      port,    then the constructor will try to derive    Proto from the
      service name.     As a last resort Proto    "tcp" is assumed.  The
      Type parameter will be deduced from Proto if not specified.

      If the constructor is    only passed a single argument, it is
      assumed to be    a PeerAddr specification.

      Examples:

         $sock = IO::Socket::INET->new(PeerAddr => 'www.perl.org',
                       PeerPort => 'http(80)',
                       Proto    => 'tcp');

         $sock = IO::Socket::INET->new(PeerAddr => 'localhost:smtp(25)');

         $sock = IO::Socket::INET->new(Listen    =>    5,
                       LocalAddr =>    'localhost',
                       LocalPort =>    9000,
                       Proto     =>    'tcp');

         $sock = IO::Socket::INET->new('127.0.0.1:25');


      MMMMEEEETTTTHHHHOOOODDDDSSSS

      sockaddr ()
          Return the address part of the sockaddr structure    for
          the socket





     Page 3                        (printed 10/23/98)






     IIIIOOOO::::::::SSSSoooocccckkkkeeeetttt((((3333))))   22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))     IIIIOOOO::::::::SSSSoooocccckkkkeeeetttt((((3333))))



      sockport ()
          Return the port number that the socket is    using on the
          local host

      sockhost ()
          Return the address part of the sockaddr structure    for
          the socket in a text form    xx.xx.xx.xx

      peeraddr ()
          Return the address part of the sockaddr structure    for
          the socket on the    peer host

      peerport ()
          Return the port number for the socket on the peer    host.

      peerhost ()
          Return the address part of the sockaddr structure    for
          the socket on the    peer host in a text form xx.xx.xx.xx

      IIIIOOOO::::::::SSSSoooocccckkkkeeeetttt::::::::UUUUNNNNIIIIXXXX

      IO::Socket::UNIX provides a constructor to create an AF_UNIX
      domain socket    and some related methods. The constructor can
      take the following options

          Type      Type of socket (eg SOCK_STREAM or SOCK_DGRAM)
          Local      Path to local    fifo
          Peer      Path to peer fifo
          Listen      Create a listen socket


      MMMMEEEETTTTHHHHOOOODDDDSSSS

      hostpath()
          Returns the pathname to the fifo at the local end

      peerpath()
          Returns the pathanme to the fifo at the peer end

     SSSSEEEEEEEE AAAALLLLSSSSOOOO
      the _S_o_c_k_e_t manpage, the _I_O::_H_a_n_d_l_e manpage

     AAAAUUUUTTTTHHHHOOOORRRR
      Graham Barr <_G_r_a_h_a_m._B_a_r_r@_t_i_u_k._t_i._c_o_m>

     CCCCOOOOPPPPYYYYRRRRIIIIGGGGHHHHTTTT
      Copyright (c)    1996 Graham Barr. All rights reserved. This
      program is free software; you    can redistribute it and/or
      modify it under the same terms as Perl itself.






     Page 4                        (printed 10/23/98)






     IIIIOOOO::::::::SSSSoooocccckkkkeeeetttt((((3333))))   22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))     IIIIOOOO::::::::SSSSoooocccckkkkeeeetttt((((3333))))























































     Page 5                        (printed 10/23/98)